Implements complete deployment workflow for deploying OpenClaw to existing servers
without provisioning new Hetzner instances. Enables integration testing of Ansible
playbooks and deployment to any server with SSH access.

New scripts:
- run-deploy.sh: Deploy OpenClaw using SSH key and inventory file
  - Auto-onboards by default (--skip-onboard to disable)
  - Creates instance artifacts automatically
  - Supports custom instance names via INSTANCE_NAME_OVERRIDE

- connect-instance.sh: Connect to instances and run OpenClaw commands
  - Reads instance artifacts to get connection details
  - Supports interactive onboard/setup/shell access
  - Can use custom IP/key via --ip and --key flags

- create-inventory.sh: Generate Ansible inventory from IP address
  - Simple wrapper to create inventory files
  - Validates IP format

- cleanup-ssh-key.yml: Manage SSH keys in Hetzner Cloud
  - List all SSH keys
  - Delete specific keys by name

Improvements:
- run-hetzner.sh: Add prerequisite checks for Python 3.12, Ansible, dependencies
- hetzner-finland-fast.yml:
  - Remove unsupported 'force' parameter from ssh_key module
  - Add debug task to show provisioning parameters

Complete workflow:
1. Create inventory: ./create-inventory.sh <IP> inventory.ini
2. Deploy + onboard: ./run-deploy.sh -k <key> -i inventory.ini
3. Or connect later: ./connect-instance.sh <instance-name> onboard

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Add comprehensive documentation for the new CLI deployment workflow:

- Quick Start section for deploying to existing servers
- Detailed command documentation for run-deploy.sh, connect-instance.sh, create-inventory.sh
- Complete workflow examples showing end-to-end deployment
- Updated file structure with new scripts
- Enhanced requirements section with Python 3.12+ setup
- Updated TLDR with both deployment methods

Key improvements:
- Emphasizes CLI deployment as recommended approach for testing
- Documents auto-onboard feature (default behavior)
- Shows how to skip onboarding with --skip-onboard
- Provides clear setup instructions for Python virtualenv
- Includes prerequisite checking information

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Create setup.sh to automate environment setup:
- Automatically detects Python 3.12+ (checks python3.12, python3, python, pyenv)
- Creates virtual environment if needed
- Installs all Python dependencies from requirements.txt
- Installs Ansible Hetzner collection
- Provides helpful error messages if Python 3.12+ not found
- Shows installation instructions for pyenv, apt, and brew

Update prerequisite checks:
- run-deploy.sh: Suggest running ./setup.sh if prerequisites missing
- run-hetzner.sh: Suggest running ./setup.sh if prerequisites missing

Update README:
- Replace manual setup steps with ./setup.sh one-liner
- Document what setup.sh does and how it works
- Update Quick Start, Requirements, Complete Workflows, and TLDR
- Emphasize simplicity: just run ./setup.sh

User experience improvements:
- No need to know about venv, pip, or ansible-galaxy
- No need to find the right Python binary
- Just run ./setup.sh and everything is installed
- Clear errors if Python 3.12+ not available

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Transform run-deploy.sh into a true one-command solution that:
- Auto-installs dependencies (Python 3.12+, venv, Ansible, collections)
- Accepts IP address directly as positional argument
- Accepts instance name via -n/--name flag
- Auto-generates temporary inventory files
- Maintains full backward compatibility with inventory files

New workflow: ./run-deploy.sh <IP> -k <key> -n <name>
Old workflow still works: ./run-deploy.sh -k <key> -i <inventory>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Merge changes from main while preserving all deployment infrastructure:
- Add LICENSE file (GNU AGPL v3)
- Update README with Discord and Twitter/X community links
- Update website Footer with correct social links
- Keep all CLI deployment scripts and infrastructure
- Keep all Ansible playbooks and requirements

No deployment functionality removed - all features intact.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Move all CLI scripts and Ansible playbooks into a dedicated cli/ directory:
- All shell scripts (.sh files)
- All Ansible playbooks (.yml files)
- ansible.cfg configuration

Changes:
- Created cli/ directory structure
- Moved 16 files: scripts, playbooks, and config
- Updated all scripts to cd to correct directory on startup
- Added path resolution for user-provided arguments (SSH keys, inventory)
- Updated README, PROVISION.md, HETZNER_SETUP.md with new paths
- Updated File Structure section in README
- All scripts reference ../instances/ and ../venv/ correctly

User workflow remains simple:
  ./cli/run-deploy.sh <IP> -k <key> -n <name>

Tested and verified:
- Deployment works correctly with new structure
- Path resolution handles relative and absolute paths
- Instance artifacts created successfully

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Document the complete one-command deployment system:
- Auto-setup functionality and flow
- Direct IP support and path resolution
- Instance naming and artifact management
- Command-line interface and options
- All deployment phases with timing
- Error handling and troubleshooting
- File organization rationale
- Security considerations
- Testing scenarios

Comprehensive reference for understanding the deployment architecture.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

This spec describes the transition from native pnpm installation to
Docker container-based deployment with a hybrid approach:

Key Features:
- Development mode: Build image on remote server (rapid iteration)
- Production mode: Pull from registry (version control)
- Non-root container execution (UID 1000:1000)
- Docker Compose v2 compatibility
- Custom image build process for security vetting

Technical Details:
- Base: Debian Bookworm (node:22-bookworm)
- Mount paths: /home/node (not /root)
- Two services: openclaw-cli (on-demand) and openclaw-gateway (daemon)
- Comprehensive Ansible playbook changes
- Enhanced wrapper script with error handling

Architecture:
- Separates CLI container (interactive) from gateway (long-running)
- Volume mounts for data persistence
- Localhost-only port binding (SSH tunnel for remote access)
- Health checks using OpenClaw commands

Implementation Strategy:
Phase 1: Development mode for testing and iteration
Phase 2: Production mode with registry deployment

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

This commit adds complete specifications for clawctl, the Node.js/TypeScript
CLI tool that will replace our Python/Ansible deployment system.

Three specification documents:

1. clawctl-strategy.md - Strategic vision and motivation
   - Why Node.js/npm over Python/Ansible
   - Design principles and goals
   - Migration path from current system

2. clawctl-spec.md - Technical implementation specification
   - 10-phase deployment flow with detailed commands
   - Docker containerization with UID matching
   - Idempotency and error recovery system
   - Resume capability for failed deployments
   - SSH operations and file uploads
   - Configuration management

3. clawctl-cli-spec.md - Complete CLI interface design
   - Full command structure (deploy, list, status, logs, etc.)
   - Instance management lifecycle
   - Gateway operations (start, stop, restart, logs)
   - OpenClaw operations (onboard, exec, shell)
   - Connection management (connect, tunnel)
   - Configuration system (files + env vars)

Key design decisions finalized:
- Root SSH access required (simplifies privilege handling)
- Create dedicated 'roboclaw' system user (UID 1000) for containers
- Docker Compose with runtime variable substitution
- Instance artifacts with local/global fallback
- All operations idempotent and resumable
- Configuration hierarchy: flags > env vars > config files > defaults
- No wrapper script needed (clawctl is the interface)

Implementation-ready specifications with:
- Detailed command syntax and examples
- Error handling and recovery strategies
- Exit codes by phase
- Configuration precedence rules
- Per-phase idempotency checks

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Replace Python/Ansible deployment system with a single-command Node.js CLI
tool that deploys OpenClaw via Docker and SSH.

Key features:
- One-command deployment: npx clawctl deploy <IP> --key <path>
- Idempotent operations with resume capability
- Docker-first with non-root containers
- Interactive onboarding via SSH tunnel
- State management for failure recovery

Implementation:
- 10-phase deployment orchestrator
- SSH operations with PTY support
- Docker Compose generation with runtime variable substitution
- Configuration hierarchy: flags > env > files > defaults
- Instance artifact management

Testing fixes:
- Corrected docker-compose.yml to match OpenClaw structure
- Fixed --force flag to properly reset deployment state
- Fixed gateway startup to use --force-recreate
- Fixed onboarding completion check (openclaw.json not config.json)
- Improved health check to work before onboarding completes

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Remove IMPLEMENTATION-PROMPT.md as implementation is complete.

Update TODO-clawctl-v1.md with all fixes applied during testing:
- Force flag now properly deletes state
- Container recreation with --force-recreate
- Correct config filename (openclaw.json)
- Health check without authentication before onboarding
- Mark all testing phases as complete

Status: 12/12 tasks complete, ready for final end-to-end test.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Features:
- Auto-connect to dashboard after deployment
  - Interactive Y/n prompt
  - SSH tunnel creation on port 18789
  - Cross-platform browser opening (macOS/Linux/Windows)
  - Automatic pairing request detection (2s polling, 60s timeout)
  - Auto-approval of first new device pairing
  - Graceful Ctrl+C handling
  - New --no-auto-connect flag to skip

- Implement --clean flag functionality
  - Stop and remove all Docker containers
  - Remove OpenClaw Docker images
  - Delete roboclaw user and home directory
  - Clean up deployment state files
  - Provides fresh deployment slate

Documentation:
- Add CHANGELOG.md tracking v1.0.0 and v1.0.1 releases
- Update clawctl-cli-spec.md with auto-connect documentation
- Update clawctl-spec.md with technical details
- Mark specs as Active (v1.0.1 implemented)

Infrastructure:
- Add .gitignore for clawctl (instances/, dist/, node_modules/)
- New module: src/lib/auto-connect.ts (tunnel, browser, pairing logic)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Fixed two issues preventing auto-connect from working:

1. --no-auto-connect flag defaulting incorrectly
   - Removed incorrect default value causing flag to always disable auto-connect
   - Commander.js negatable options should not have explicit defaults

2. Missing authentication token in browser URL
   - Added token parameter to autoConnect() function
   - Browser now opens with ?token= query parameter for automatic auth
   - Falls back to plain URL if token unavailable

Tested: Auto-connect now prompts user, opens browser with token, and waits
for device pairing.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Specs Updates:
- Remove version markers from section headers to reduce maintenance overhead
- Fix phase numbering throughout clawctl-spec.md (phases 0-10, not 1-10)
- Clarify auto-connect is post-deployment feature, not a deployment phase
- Add Phase 10: Finalize Deployment section
- Update all state file examples, error scenarios, and phase references

Version Bump:
- Bump package.json to 1.0.1 (reflects auto-connect feature addition)
- Update CLI version in src/index.ts to match

All specs now accurately reflect the current clawctl deployment implementation
with correct phase numbering and auto-connect behavior.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Created two documentation files to improve LLM efficiency when working on the project:

CLAUDE.md:
- Instructions for LLMs on when to read specs vs. code
- Clear routing logic: concrete tasks → read code, questions → read specs
- Key technical patterns (ES modules, template literals, Docker Compose variables)
- Workflow decision tree
- Quick reference links to specs and memory

specs/PRIMER.md:
- Routing guide to help LLMs find the right specification file
- Quick routing table mapping query types to specs
- Comprehensive topic index (40+ topics alphabetically sorted)
- Query pattern examples with reasoning
- Reading strategies for common tasks
- Per-spec summaries with "when to read" guidance

Benefits:
- Reduces time spent reading unnecessary specs
- Provides fast routing to relevant documentation
- Prevents common mistakes with key patterns documented upfront
- Maintains context via memory system links

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Moved PRIMER.md from specs/ to root directory since it's a navigation/routing
document rather than a specification itself.

Changes:
- git mv specs/PRIMER.md -> PRIMER.md
- Updated 3 references in CLAUDE.md to reflect new location

Rationale:
- PRIMER.md and CLAUDE.md are companion navigation documents
- Both serve to help LLMs work efficiently with the project
- Keeping them together in the root makes them more discoverable
- specs/ directory now contains only actual specifications

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

This commit adds three new specification documents generated by LLM agents
and integrates them into the project's documentation infrastructure.

New Specifications (234KB total):
- specs/openclaw-architecture.md (89KB) - OpenClaw system architecture
  * What OpenClaw is and how it works
  * CLI and Gateway service details
  * Gateway API reference
  * Device pairing system
  * Configuration internals

- specs/testing-guide.md (82KB) - Testing and development guide
  * Development environment setup
  * Testing workflows and techniques
  * Debugging strategies
  * Platform-specific testing

- specs/troubleshooting-guide.md (63KB) - Deployment troubleshooting
  * Phase-by-phase troubleshooting (all 11 phases)
  * Quick diagnosis table
  * Recovery strategies
  * Common error solutions

Spec Generation Infrastructure:
- specs/prompts/README.md - How to use prompts
- specs/prompts/openclaw-architecture-prompt.md
- specs/prompts/testing-guide-prompt.md
- specs/prompts/troubleshooting-guide-prompt.md

Integration Updates:
- PRIMER.md - Added routing to all 3 new specs
  * Updated Quick Routing Table
  * Added spec overviews (#6, #7, #8)
  * Added 10+ Topic Index entries
  * Added 8 query pattern examples
  * Added 3 reading strategy tasks

- CLAUDE.md - Updated AI instructions
  * Added 3 new specs to reference section
  * Enhanced "Read Specs When" guidance
  * Updated file structure
  * Fixed code paths

Testing & Tracking:
- TESTING-TODOS.md - Comprehensive testing checklist (100+ tasks)
- POST-SPEC-INTEGRATION-SUMMARY.md - Integration work summary

Impact:
- Documentation coverage: 62.5% → 100%
- All key areas now documented
- Clear testing, troubleshooting, and architecture guidance

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Move LLM navigation and spec generation tools into dedicated .llm/ directory
for better organization and clarity. CLAUDE.md remains at root as the main
entry point for AI assistants.

Changes:
- Move PRIMER.md → .llm/NAVIGATION.md (spec routing guide)
- Move specs/prompts/ → .llm/prompts/ (spec generation prompts)
- Create .llm/README.md (directory documentation)
- Update CLAUDE.md references to new paths

File Structure:
```
.llm/
├── README.md                    # LLM directory documentation
├── NAVIGATION.md                # Spec routing guide (was PRIMER.md)
└── prompts/                     # Spec generation prompts
    ├── README.md
    ├── openclaw-architecture-prompt.md
    ├── testing-guide-prompt.md
    └── troubleshooting-guide-prompt.md
```

Benefits:
- Clear separation: .llm/ = AI tools, specs/ = human docs
- Hidden from casual browsing (follows .github/, .claude/ pattern)
- CLAUDE.md at root remains discoverable
- Easy to add more LLM tools later

Updated References:
- CLAUDE.md now points to .llm/NAVIGATION.md
- Workflow diagram updated
- File structure section reorganized
- Quick reference links updated

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Brings in website updates from main:
- Remove ClawFleet references
- Add mobile navbar
- Add RoboClaw blog with initial post

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Changes:
- Rewrite root README.md (600 → 80 lines) focusing on clawctl
- Expand clawctl/README.md (147 → 350 lines) with comprehensive sections:
  - "What is OpenClaw?" explaining the platform
  - "What Happens During Deployment" - human-readable phase descriptions
  - "After Deployment" - auto-connect workflow and manual access
  - "Error Recovery" - automatic resume, --force, --clean options
  - "Troubleshooting" - quick reference table for common issues
  - "Security" - container isolation and authentication details
- Add missing --no-auto-connect option to usage documentation
- Unify license: Change clawctl from Apache-2.0 to AGPL-3.0
- Create clawctl/LICENSE file (copy of root AGPL-3.0 license)
- Create ansible-deployment/README.md deprecation notice
- Emphasize community-driven development throughout documentation

All documentation now focuses on the modern npx clawctl workflow.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>